/**
 * <h3>ThemeMapper</h3>
 * <p> 大赛信息数据访问层接口 </p>
 *
 * <h3>功能描述</h3>
 * <p> 定义对数据库表 theme_competition 的基本操作方法，包括增删改查 </p>
 * <p> 配合 MyBatis Plus 实现 ORM 映射与持久化操作 </p>
 *
 * <h3>元数据</h3>
 * <ul>
 *     <li> 作者：郭强 </li>
 *     <li> 创建日期：2025年05月18日 14:20:15 </li>
 * </ul>
 *
 * <h3>其他信息</h3>
 * <ul>
 *     <li> 继承自：{@link BaseMapper<ThemeDTO>} </li>
 *     <li> 示例代码：{@code List<Theme> list = themeMapper.selectThemeList(dto);} </li>
 * </ul>
 *
 * @apiNote 方法签名应与 XML 文件中的 id 保持一致，以确保正确绑定
 * @implSpec 使用泛型类型 ThemeDTO 进行实体映射
 * @since v1.0.0.0
 */
package com.dnndo.system.mapper;

import com.baomidou.mybatisplus.core.mapper.BaseMapper;
import com.dnndo.system.domain.dto.ThemeDTO;
import com.dnndo.system.domain.dto.ThemeInfoDTO;
import com.dnndo.system.domain.dto.WorkDTO;
import com.dnndo.system.domain.vo.*;
import org.apache.ibatis.annotations.Mapper;
import org.apache.ibatis.annotations.Param;

import java.util.List;

/**
 * 大赛数据访问层接口
 */
@Mapper
public interface ThemeMapper extends BaseMapper<ThemeDTO> {

    /**
     * 查询所有或符合条件的大赛列表
     * @param dto 查询条件封装对象
     * @return List<Theme> 符合条件的大赛信息列表
     */
    List<ThemeDTO> selectThemeList(ThemeDTO dto);
    /**
     * 根据ID查询大赛信息
     * @param themeId 大赛唯一标识符
     * @return ThemeDTO 大赛信息
     */
    ThemeDTO selectThemeListById(Long themeId);

    /**
     * 新增大赛信息
     * @param dto 封装新增数据的DTO对象
     * @return int 受影响的记录数
     */
    int insertTheme(ThemeDTO dto);

    /**
     * 修改大赛信息
     * @param dto 封装更新数据的DTO对象
     * @return int 受影响的记录数
     */
    int updateThemeById(ThemeDTO dto);

    /**
     * 删除大赛信息
     * @param themeId 大赛ID
     * @return int 受影响的记录数
     */
    int deleteThemeById(Integer themeId);

    /**
     * 查询所有主题大赛信息（中文）
     * 逻辑说明：
     * 1. 查询所有主题大赛信息，返回中文内容。
     *
     * @param userId 用户ID，可用于个性化筛选
     * @return List<ThemeInfoVOZH> 主题大赛信息列表（中文）
     */
    List<ThemeInfoVOZH> competition(@Param("userId") Integer userId, @Param("schoolId") String schoolId);

    /**
     * 查询所有主题大赛信息（英文）
     * 逻辑说明：
     * 1. 查询所有主题大赛信息，返回英文内容。
     *
     * @param userId 用户ID，可用于个性化筛选
     * @return List<ThemeInfoVOEN> 主题大赛信息列表（英文）
     */
    List<ThemeInfoVOEN> competitionEn(@Param("userId") Integer userId, @Param("schoolId") String schoolId);

    /**
     * 根据主题ID查询主题大赛详情（中文）
     * 逻辑说明：
     * 1. 查询指定主题ID和用户ID的主题大赛中文详情。
     *
     * @param themeId 主题ID
     * @param userId 用户ID
     * @return ThemeQueryVOZH 主题大赛详情（中文）
     */
    ThemeQueryVOZH theme(@Param("themeId") Integer themeId, @Param("userId") Integer userId);

    /**
     * 根据主题ID查询主题大赛详情（英文）
     * 逻辑说明：
     * 1. 查询指定主题ID和用户ID的主题大赛英文详情。
     *
     * @param themeId 主题ID
     * @param userId 用户ID
     * @return ThemeQueryVOEN 主题大赛详情（英文）
     */
    ThemeQueryVOEN themeEn(@Param("themeId") Integer themeId, @Param("userId") Integer userId);

    /**
     * 查询当前主题大赛的所有作品（中文）
     * 逻辑说明：
     * 1. 查询指定主题ID下的所有作品，返回中文内容。
     *
     * @param themeId 主题ID
     * @return List<WorkDTO> 作品列表（中文）
     */
    List<WorkDTO> work(Integer themeId);

    /**
     * 查询当前主题大赛的所有作品（英文）
     * 逻辑说明：
     * 1. 查询指定主题ID下的所有作品，返回英文内容。
     *
     * @param themeId 主题ID
     * @return List<WorkDTO> 作品列表（英文）
     */
    List<WorkDTO> workEn(Integer themeId);

    /**
     * 查询大赛总数
     * 逻辑说明：
     * 1. 统计符合条件的大赛总数。
     *
     * @param dto 查询参数
     * @return int 大赛总数
     */
    int countCompetition(ThemeInfoDTO dto);

    /**
     * 获取当前主题大赛下所有作品总数
     * 逻辑说明：
     * 1. 统计指定主题下的作品总数。
     *
     * @param dto 查询参数
     * @return int 作品总数
     */
    int countTheme(WorkDTO dto);

    /**
     * 查询所有已结束且排名状态为0（未计算）的主题ID
     *
     * @return List<Integer> 包含符合条件的主题ID的列表
     */
    List<Integer> selectExpiredAndUnrankedThemes();

    /**
     * 更新主题的排名状态为1（已计算）
     *
     * @param themeId 要更新状态的主题ID
     * @return int 受影响的行数，成功则为1
     */
    int updateThemeRanked(@Param("themeId") Integer themeId);
}
